autodoc: preserve docstrings for type aliases (fix) [swev-id: sphinx-doc__sphinx-9229]#102
Open
rowan-stein wants to merge 2 commits intosphinx-doc__sphinx-9229from
Open
autodoc: preserve docstrings for type aliases (fix) [swev-id: sphinx-doc__sphinx-9229]#102rowan-stein wants to merge 2 commits intosphinx-doc__sphinx-9229from
rowan-stein wants to merge 2 commits intosphinx-doc__sphinx-9229from
Conversation
noa-lucent
requested changes
Dec 27, 2025
noa-lucent
left a comment
There was a problem hiding this comment.
Thanks for tightening up the alias handling and adding coverage. One blocking issue remains: importing TypeAlias directly from typing breaks on the Python releases we still support (py36–py39). Please guard the import just like you already do for TypeAliasType (try typing, fall back to typing_extensions, otherwise None) so sphinx.ext.autodoc keeps importing on those runtimes.
noa-lucent
approved these changes
Dec 27, 2025
noa-lucent
left a comment
There was a problem hiding this comment.
Import guard looks good now. Thanks for following up!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Preserve module-level docstrings for type aliases documented with next-line triple-quoted strings. Previously, aliases to class/type objects (e.g.,
int) were documented only as “alias of …”, ignoring the alias docstrings.Related Issue: #101
Reproduction steps
SimpleInt = intfollowed by a next-line docstringMyInt: TypeAlias = intfollowed by a next-line docstringIntListOrUnion: TypeAlias = Union[List[int], int]followed by a next-line docstring.. automodule::using:members:and:undoc-members:.Observed behavior (before fix)
SimpleInt: only “alias of int” (alias docstring ignored)MyInt: only “alias of int” (alias docstring ignored)IntListOrUnion: shows alias docstring and “alias of Union[List[int], int]”Root cause
ClassDocumenterfor aliases to class/type objects and setsdoc_as_attr, but it does not merge module-level alias docstrings fromModuleAnalyzer. Aliases to typing expressions useDataDocumenter, which preserves module-level docstrings viaattr_docs.Fix
DataDocumenterfor module-level aliases when a module-level alias docstring exists or aTypeAliasannotation is present and the alias points to a type/class with a different__name__. This preserves alias docstrings.ClassDocumenterstill handles such aliases underdoc_as_attr, merge the module-level alias docstring retrieved fromModuleAnalyzerbefore appending “alias of …”.Tests
tests/roots/test-ext-autodoc/target/type_alias_docstrings.pywith aliases covering annotated, unannotated, complex typing expressions, and docstring-free cases.tests/test_ext_autodoc_automodule.py::test_type_alias_docstringsverifying that all alias docstrings are rendered and “alias of …” lines are included.Local test environment notes
Expected outcome